/*
 * ChannelFacade.java    0.0.1    17/set/2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */ 
package org.mentalsmash.tazio.net.cs.server.impl;

import org.mentalsmash.tazio.net.cs.server.ProtocolHandler;

/**
 * A ChannelFacade represents an abstraction of a channel that includes an input queue and
 * an output queue for that channel, and methods to safely access those queues.
 * <p>
 * This class and all the classes in this package are largely inspired to the presentation
 * "How To Build A Scalable NIO Server, Mark II" by Ron Hitchens (http://ronsoft.com)
 * </p>
 * @version    0.0.1    17/set/2009 
 * @author Andrea Reale <andrea.reale@gmail.com>
 */
public interface ChannelFacade {
	/**
	 * The queue in wich input for the channel is stored. This queue does know nothing about
	 * how messages are formatted according to the application protocol
	 * @return The queue in wich input for the channel is stored
	 */
	InputQueue getInputQueue();
	/**
	 * This queue contains the data to be sent out from the channel. When the channel is ready to
	 * accept writes the contents of this queue will be sent over the channel. There's no guarantee
	 * that the entire queue will be sent in a single message.
	 * @return the output queue associated with the channel
	 */
	OutputQueue getOutputQueue();
	
	/**
	 * Set the handler that will manage incoming data for this channel. This handler will be used to
	 * recognize and separate complete protocol messages inside the stream of incoming data.
	 * @param handler the protocol handler to be associated with this channel
	 */
	void setProtocolHandler(ProtocolHandler handler);
	/**
	 * Return the bit mask that specifies wich are the operations this channel is interested in.
	 * The possible operations are  those defined in java.nio.channels.SelectionKey:
	 * (i.e. SelectionKey.OP_ACCEPT, SelectionKey.OP_CONNECT, SelectionKey.OP_READ, SelectionKey.OP_WRITE)
	 * @return the operations this channel is interested in
	 */
	int getInterestOps();
	
	/**
	 * Modifies the set of operation this channel is interested into.
	 * The possible operations are  those defined in java.nio.channels.SelectionKey:
	 * (i.e. SelectionKey.OP_ACCEPT, SelectionKey.OP_CONNECT, SelectionKey.OP_READ, SelectionKey.OP_WRITE)
	 * @param opsToAdd the bit mask containing the operations to add (e.g. (OP_READ | OP_WRITE) for a 
	 *                 read-write channel )
	 * @param opsToRemove the bit mask containing the operations the channel is no longere interested into 
	 *                    (e.g. (OP_WRITE) for a channel that's no longer interested in writing )
	 */
	void modifyInterestOps(int opsToAdd, int opsToRemove);
	
	/**
	 * Returns true if the underlying channel implements the interface ReadableByteChannel
	 * @return true if the underlying channel implements the interface ReadableByteChannel
	 */
	boolean isReadable();
	
	/**
	 * Returns true if the underlying channel implements the interface WritableByteChannel
	 * @return true if the underlying channel implements the interface WritableByteChannel
	 */
	boolean isWritable();
	
	
}
